篇首语:本文由编程笔记#小编为大家整理,主要介绍了使用 Spring 创建“Hello, World”超媒体驱动的 REST Web 服务相关的知识,希望对你有一定的参考价值。
本指南将引导您完成使用 Spring 创建“Hello, World”超媒体驱动的 REST Web 服务的过程。
超媒体是 REST 的一个重要方面。它允许您构建在很大程度上分离客户端和服务器的服务,并让它们独立发展。为 REST 资源返回的表示形式不仅包含数据,还包含指向相关资源的链接。因此,表示的设计对于整体服务的设计至关重要。
您将使用 Spring HATEOAS 构建一个超媒体驱动的 REST 服务:一个 API 库,可用于创建指向 Spring MVC 控制器的链接,构建资源表示,并控制它们如何呈现为受支持的超媒体格式(如 HAL)。
该服务将接受位于 的 HTTP GET 请求。http://localhost:8080/greeting
它将使用问候语的 JSON 表示形式进行响应,该问候语使用最简单的超媒体元素(指向资源本身的链接)进行丰富。以下清单显示了输出:
"content":"Hello, World!",
"_links":
"self":
"href":"http://localhost:8080/greeting?name=World"
响应已指示您可以使用查询字符串中的可选参数自定义问候语,如以下清单所示:name
http://localhost:8080/greeting?name=User
参数值将覆盖 的默认值,并反映在响应中,如以下清单所示:name
World
"content":"Hello, User!",
"_links":
"self":
"href":"http://localhost:8080/greeting?name=User"
像大多数春天一样入门指南,您可以从头开始并完成每个步骤,也可以绕过您已经熟悉的基本设置步骤。无论哪种方式,您最终都会得到工作代码。
要从头开始,请继续从 Spring 初始化开始.
要跳过基础知识,请执行以下操作:
git clone https://github.com/spring-guides/gs-rest-hateoas.git
gs-rest-hateoas/initial
完成后,您可以根据 中的代码检查结果。gs-rest-hateoas/complete
你可以使用这个预初始化项目,然后单击生成以下载 ZIP 文件。此项目配置为适合本教程中的示例。
手动初始化项目:
如果您的 IDE 集成了 Spring Initializr,则可以从 IDE 完成此过程。 |
您也可以从 Github 分叉项目,然后在 IDE 或其他编辑器中打开它。 |
由于您将使用 JSON 发送和接收信息,因此需要一个 JSON 库。在本指南中,您将使用 Jayway JsonPath 库。
要将库包含在 Maven 构建中,请将以下依赖项添加到文件中:pom.xml
以下清单显示了完成的文件:pom.xml
要在 Gradle 构建中包含该库,请将以下依赖项添加到您的文件中:build.gradle
testCompile com.jayway.jsonpath:json-path
以下清单显示了完成的文件:build.gradle
plugins
id org.springframework.boot version 3.0.0
id io.spring.dependency-management version 1.1.0
id java
group = com.example
version = 0.0.1-SNAPSHOT
sourceCompatibility = 17
repositories
mavenCentral()
dependencies
implementation org.springframework.boot:spring-boot-starter-hateoas
testImplementation org.springframework.boot:spring-boot-starter-test
test
useJUnitPlatform()
设置项目和生成系统后,可以创建 Web 服务了。
从考虑服务交互开始该过程。
该服务将公开资源以处理请求,可以选择在查询字符串中使用参数。请求应返回正文中包含 JSON 的响应,以表示问候语。/greeting
GET
name
GET
200 OK
除此之外,资源的 JSON 表示形式将使用属性中的超媒体元素列表进行丰富。最基本的形式是指向资源本身的链接。表示形式应类似于以下清单:_links
"content":"Hello, World!",
"_links":
"self":
"href":"http://localhost:8080/greeting?name=World"
是问候语的文本表示形式。该元素包含一个链接列表(在本例中,恰好是一个具有关系类型和指向所访问资源的属性的链接)。content
_links
rel
href
若要对问候语表示形式进行建模,请创建资源表示形式类。由于该属性是表示模型的基本属性,Spring HATEOAS 附带了一个基类(称为),该基类允许您添加 的实例并确保它们如前所示呈现。_links
RepresentationModel
Link
创建一个普通的旧 java 对象,该对象扩展并添加内容的字段和访问器以及构造函数,如以下列表 (from ) 所示:RepresentationModel
src/main/java/com/example/resthateoas/Greeting.java
package com.example.resthateoas; 正如您将在本指南后面看到的那样,Spring 将使用 Jackson JSON 库自动将类型的实例编组到 JSON 中。 接下来,创建将提供这些问候语的资源控制器。 在Spring构建RESTful Web服务的方法中,HTTP请求由控制器处理。组件由@RestController注释,它结合了@Controller和@ResponseBody附注。以下 (from ) 通过返回类的新实例来处理请求: package com.example.resthateoas; 这个控制器简洁明了,但还有很多事情要做。我们一步一步地分解它。 注释可确保将 HTTP 请求映射到该方法。 上面的示例未指定 vs. 、 等,因为默认情况下会映射所有 HTTP 操作。用于缩小此映射范围。在这种情况下,您还需要 . 由于类上存在注释,因此隐式 方法实现中最有趣的部分是如何创建指向控制器方法的链接以及如何将其添加到表示模型中。两者都是静态方法,可让您伪造控制器上的方法调用。返回的将检查控制器方法的映射注释,以准确构建方法映射到的 URI。 Spring HATEOAS 尊重各种标头。如果您将Spring HATEOAS服务放在代理后面,并使用标头正确配置它,则生成的链接将被正确格式化。 调用 创建添加到表示模型的实例。 该方法使用 Spring Boot 的方法启动应用程序。您是否注意到没有一行 XML?也没有文件。此 Web 应用程序是 100% 纯 Java,您无需处理配置任何管道或基础结构。 您可以使用 Gradle 或 Maven 从命令行运行应用程序。您还可以构建一个包含所有必需依赖项、类和资源的可执行 JAR 文件并运行该文件。通过构建可执行 jar,可以轻松地在整个开发生命周期中跨不同环境等将服务作为应用程序进行交付、版本控制和部署。 如果使用 Gradle,则可以使用 .或者,您可以使用 JAR 文件生成 JAR 文件,然后运行该文件,如下所示: java -jar build/libs/gs-rest-hateoas-0.1.0.jar 如果使用 Maven,则可以使用 运行应用程序。或者,您可以使用 JAR 文件生成 JAR 文件,然后运行该文件,如下所示: java -jar target/gs-rest-hateoas-0.1.0.jar 此处描述的步骤将创建一个可运行的 JAR。你也可以构建经典 WAR 文件. 将显示日志记录输出。该服务应在几秒钟内启动并运行。 现在服务已启动,请访问http://localhost:8080/greeting,您应该在其中看到以下内容: 通过访问以下 URL 提供查询字符串参数:。请注意属性的值如何从 更改为 以及链接的属性如何反映该更改,如以下清单所示: 此更改表明 中的排列按预期工作。参数的默认值为 ,但始终可以通过查询字符串显式重写。 祝贺!您刚刚使用 Spring HATEOS 开发了一个超媒体驱动的 RESTful Web 服务。
import org.springframework.hateoas.RepresentationModel;
import com.fasterxml.jackson.annotation.JsonCreator;
import com.fasterxml.jackson.annotation.JsonProperty;
public class Greeting extends RepresentationModel
private final String content;
@JsonCreator
public Greeting(@JsonProperty("content") String content)
this.cOntent= content;
public String getContent()
return content;
Greeting
创建 REST 控制器
GreetingController
src/main/java/com/example/resthateoas/GreetingController.java
GET
/greeting
Greeting
import static org.springframework.hateoas.server.mvc.WebMvcLinkBuilder.*;
import org.springframework.http.HttpEntity;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
@RestController
public class GreetingController
private static final String TEMPLATE = "Hello, %s!";
@RequestMapping("/greeting")
public HttpEntity
@RequestParam(value = "name", defaultValue = "World") String name)
Greeting greeting = new Greeting(String.format(TEMPLATE, name));
greeting.add(linkTo(methodOn(GreetingController.class).greeting(name)).withSelfRel());
return new ResponseEntity<>(greeting, HttpStatus.OK);
@RequestMapping
/greeting
greeting()
GET
PUT
POST
@RequestMapping
@GetMapping("/greeting")
import org.springframework.web.bind.annotation.GetMapping;
@RequestParam
将查询字符串参数的值绑定到方法的参数中。此查询字符串参数隐式不是因为使用了该属性。如果请求中不存在,则使用 of。name
name
greeting()
required
defaultValue
defaultValue
World
@RestController
@ResponseBody批注将添加到方法中。这会导致 Spring MVC 将返回的内容及其有效负载 () 直接呈现给响应。greeting
HttpEntity
Greeting
linkTo(…)
methodOn(…)
ControllerLinkBuilder
LinkBuilder
X-FORWARDED-
X-FORWARDED-HOST
withSelfRel()
Link
Greeting
@SpringBootApplication
是一个方便的注释,它添加了以下所有内容:@Configuration
:将类标记为应用程序上下文的 Bean 定义源。@EnableAutoConfiguration
:告诉 Spring 引导根据类路径设置、其他 bean 和各种属性设置开始添加 bean。例如,如果 在类路径上,则此注释会将应用程序标记为 Web 应用程序并激活关键行为,例如设置 .spring-webmvc
DispatcherServlet
@ComponentScan
:告诉 Spring 在包中查找其他组件、配置和服务,让它找到控制器。com/example
main()
SpringApplication.run()
web.xml
构建可执行的 JAR
./gradlew bootRun
./gradlew build
./mvnw spring-boot:run
./mvnw clean package
测试服务
"content":"Hello, World!",
"_links":
"self":
"href":"http://localhost:8080/greeting?name=World"
name
http://localhost:8080/greeting?name=User
content
Hello, World!
Hello, User!
href
self
"content":"Hello, User!",
"_links":
"self":
"href":"http://localhost:8080/greeting?name=User"
@RequestParam
GreetingController
name
World
总结